package com.tianji.learning.service;

import com.tianji.common.domain.dto.PageDTO;
import com.tianji.common.domain.query.PageQuery;
import com.tianji.learning.domain.po.LearningLesson;
import com.baomidou.mybatisplus.extension.service.IService;
import com.tianji.learning.domain.vo.LearningLessonVO;
import com.tianji.learning.domain.vo.LearningPlanPageVO;

import java.util.List;

/**
 * <p>
 * 学生课程表 服务类
 * </p>
 *
 * @author zr
 * @since 2024-07-10
 */
public interface ILearningLessonService extends IService<LearningLesson> {

    /**
     * 为用户添加课程。
     * <p>
     * 本方法用于将指定的课程添加到指定用户的课程列表中。
     * 这用于用户报名/购买新课程，课程的添加是通过课程的ID列表来进行的，这允许一次性添加多个课程。
     *
     * @param userId    用户的ID。这个参数指定哪个用户将获得新的课程。
     * @param courseIds 课程的ID列表。这个列表中的每个ID代表一个将被添加到用户课程列表中的课程。
     */
    void addUserLessons(Long userId, List<Long> courseIds);

    /**
     * 查询我的课程列表
     *
     * @param query 分页查询条件
     * @return 分页结果，包含课程列表信息
     */
    PageDTO<LearningLessonVO> queryMyLessons(PageQuery query);

    /**
     * 查询当前正在进行的课程。
     * <p>
     * 本方法用于获取用户当前正在进行的学习课程的信息。
     *
     * @return LearningLessonVO 返回一个LearningLessonVO对象，其中包含了当前课程的信息。
     */
    LearningLessonVO queryMyCurrentLesson();

    /**
     * 根据课程ID查询指定课程
     * <p>
     * 学习视图对象（LearningLessonVO）封装了关于课程学习资料的详细信息，供获取课程信息。
     *
     * @param courseId 课程的唯一标识ID。此ID用于在数据库中定位特定课程的信息。
     * @return LearningLessonVO 包含查询到的课程学习资料信息。如果找不到匹配的资料，则返回null。
     */
    LearningLessonVO queryLessonByCourseId(Long courseId);

    /**
     * 删除课表中课程。
     * <p>
     * 用户直接删除已失效的课程
     * 用户退款后触发课表自动删除
     *
     * @param userId   需要被删除的用户的ID。这是用户在系统中的唯一标识符。
     * @param courseId 课程的ID。这是课程在系统中的唯一标识符。
     */
    void deleteCourseFromLesson(Long userId, Long courseId);

    /**
     * 根据课程ID统计学习该课程的学员数量。
     * <p>
     * 本方法通过查询数据库，统计指定课程ID对应课程的学习者数量。
     * 课程ID作为参数传入，方法返回学习该课程的学员数量。
     *
     * @param courseId 课程的唯一标识ID，用于指定查询的课程。
     * @return 返回学习该课程的学员数量，如果课程不存在或没有学员学习，则返回0。
     */
    Integer countLearningLessonByCourse(Long courseId);

    /**
     * 检查课程是否有效。
     * <p>
     * 本方法通过课程ID来判断一门课程是否有效。课程的有效性可能取决于多个因素，
     * 如课程是否已被删除、课程是否已过期等。
     *
     * @param courseId 课程的唯一标识ID。这个ID用于在数据库查找对应的课程信息。
     * @return 如果课程有效，则返回课程ID；如果课程无效，则返回null。
     */
    Long isLessonValid(Long courseId);

    LearningLesson queryByUserAndCourseId(Long userId, Long courseId);

    /**
     * 创建学习计划
     * <p>
     * 本方法用于根据指定的课程ID和学习频率创建一个新的学习计划。
     * 通过指定课程ID，我们可以确定学习计划针对的具体课程。而学习频率则用于确定学习任务的重复周期。
     *
     * @param courseId 课程ID，用于指定学习计划针对的课程。
     * @param freq     学习频率，表示学习任务的重复周期，例如每周一次。
     */
    void createLearningPlan(Long courseId, Integer freq);

    /**
     * 查询我的学习计划
     * <p>
     * 通过PageQuery参数查询用户的学习计划，返回LearningPlanPageVO对象，其中包含查询结果和分页信息。
     *
     * @param query 查询条件，包含分页和过滤条件等。
     * @return LearningPlanPageVO 对象，包含查询结果和分页信息。
     */
    LearningPlanPageVO queryMyPlans(PageQuery query);
}
